/**
 * ============日志工具模块开始===========
 * 日志记录工具 - Logger Utility
 * 
 * 功能说明：
 * - 提供统一的日志记录接口
 * - 支持不同级别的日志输出
 * - 自动添加时间戳和日志级别标识
 * - 支持开发环境的调试日志
 * 
 * 日志级别：
 * - INFO: 一般信息记录，用于记录应用程序的正常运行状态
 * - ERROR: 错误信息记录，用于记录应用程序的错误和异常
 * - WARN: 警告信息记录，用于记录潜在问题和警告
 * - DEBUG: 调试信息记录，仅在开发环境下输出
 * 
 * 应用场景：
 * - 记录用户操作和系统事件
 * - 记录错误和异常信息用于调试
 * - 记录性能指标和监控数据
 * - 记录安全相关的操作和事件
 * 
 * 设计原则：
 * - 简单易用的API接口
 * - 统一的日志格式
 * - 环境相关的日志输出控制
 * - 支持结构化日志数据
 * 
 * Provides unified logging interface with timestamp and level formatting
 */

/**
 * ============日志记录器对象开始===========
 * 日志记录器 - 提供多级别日志记录功能
 * Logger Object - Provides multi-level logging functionality
 * 
 * 特性说明：
 * - 自动格式化日志输出
 * - 包含时间戳和日志级别
 * - 支持多参数日志记录
 * - 环境相关的日志控制
 * 
 * 日志格式：
 * [LEVEL] YYYY-MM-DDTHH:mm:ss.sssZ - message ...args
 * 
 * 使用示例：
 * import { logger } from './utils/logger.js';
 * 
 * // 记录信息日志
 * logger.info('用户登录成功', { userId: 123, ip: '192.168.1.1' });
 * 
 * // 记录错误日志
 * logger.error('数据库连接失败', error);
 * 
 * // 记录警告日志
 * logger.warn('API调用频率过高', { userId: 123, count: 100 });
 * 
 * // 记录调试日志（仅开发环境）
 * logger.debug('处理请求参数', req.body);
 */
const logger = {
  /**
   * ============信息日志方法开始===========
   * 记录信息级别日志 - Log info level messages
   * 
   * @param {string} message - 日志消息内容
   * @param {...any} args - 附加的日志参数，可以是对象、数组等
   * @returns {void} 无返回值
   * 
   * 功能说明：
   * - 记录应用程序的正常运行信息
   * - 用于记录用户操作、系统事件等
   * - 输出到标准输出流（stdout）
   * - 包含时间戳和INFO级别标识
   * 
   * 使用场景：
   * - 用户登录、注册等操作记录
   * - API请求和响应记录
   * - 系统启动和关闭记录
   * - 业务流程关键节点记录
   * 
   * 使用示例：
   * logger.info('用户登录成功', { 
   *   userId: 123, 
   *   username: 'john_doe',
   *   loginTime: new Date(),
   *   ip: '192.168.1.1'
   * });
   * 
   * logger.info('API请求处理完成', {
   *   method: 'POST',
   *   url: '/api/users',
   *   duration: '150ms',
   *   status: 200
   * });
   */
  info: (message, ...args) => {
    // 输出信息级别日志，包含时间戳和级别标识 - Output info level log with timestamp and level identifier
    console.log(`[INFO] ${new Date().toISOString()} - ${message}`, ...args);
  },

  /**
   * ============错误日志方法开始===========
   * 记录错误级别日志 - Log error level messages
   * 
   * @param {string} message - 错误消息内容
   * @param {...any} args - 附加的错误参数，通常包含错误对象、堆栈信息等
   * @returns {void} 无返回值
   * 
   * 功能说明：
   * - 记录应用程序的错误和异常信息
   * - 用于记录系统故障、业务逻辑错误等
   * - 输出到标准错误流（stderr）
   * - 包含时间戳和ERROR级别标识
   * 
   * 使用场景：
   * - 数据库连接失败
   * - API调用异常
   * - 文件操作错误
   * - 业务逻辑验证失败
   * - 第三方服务调用失败
   * 
   * 使用示例：
   * logger.error('数据库连接失败', {
   *   error: error.message,
   *   stack: error.stack,
   *   database: 'mongodb://localhost:27017',
   *   timestamp: new Date()
   * });
   * 
   * logger.error('用户认证失败', {
   *   userId: 123,
   *   reason: 'Invalid token',
   *   ip: req.ip,
   *   userAgent: req.get('User-Agent')
   * });
   */
  error: (message, ...args) => {
    // 输出错误级别日志，包含时间戳和级别标识 - Output error level log with timestamp and level identifier
    console.error(`[ERROR] ${new Date().toISOString()} - ${message}`, ...args);
  },

  /**
   * ============警告日志方法开始===========
   * 记录警告级别日志 - Log warning level messages
   * 
   * @param {string} message - 警告消息内容
   * @param {...any} args - 附加的警告参数，通常包含相关上下文信息
   * @returns {void} 无返回值
   * 
   * 功能说明：
   * - 记录应用程序的警告和潜在问题
   * - 用于记录不影响正常运行但需要关注的情况
   * - 输出到标准错误流（stderr）
   * - 包含时间戳和WARN级别标识
   * 
   * 使用场景：
   * - API调用频率过高
   * - 资源使用率接近阈值
   * - 配置参数不合理
   * - 第三方服务响应缓慢
   * - 用户操作异常但不影响系统
   * 
   * 使用示例：
   * logger.warn('API调用频率过高', {
   *   userId: 123,
   *   endpoint: '/api/data',
   *   callCount: 100,
   *   timeWindow: '1分钟',
   *   threshold: 50
   * });
   * 
   * logger.warn('内存使用率较高', {
   *   currentUsage: '85%',
   *   threshold: '80%',
   *   availableMemory: '2GB',
   *   processId: process.pid
   * });
   */
  warn: (message, ...args) => {
    // 输出警告级别日志，包含时间戳和级别标识 - Output warning level log with timestamp and level identifier
    console.warn(`[WARN] ${new Date().toISOString()} - ${message}`, ...args);
  },

  /**
   * ============调试日志方法开始===========
   * 记录调试级别日志 - Log debug level messages
   * 
   * @param {string} message - 调试消息内容
   * @param {...any} args - 附加的调试参数，通常包含详细的调试信息
   * @returns {void} 无返回值
   * 
   * 功能说明：
   * - 记录应用程序的调试和开发信息
   * - 仅在开发环境（NODE_ENV=development）下输出
   * - 用于开发阶段的问题排查和代码调试
   * - 输出到标准输出流（stdout）
   * - 包含时间戳和DEBUG级别标识
   * 
   * 环境控制：
   * - 开发环境：输出调试日志
   * - 生产环境：不输出调试日志（性能考虑）
   * 
   * 使用场景：
   * - 函数参数和返回值调试
   * - 业务逻辑执行流程跟踪
   * - 数据库查询语句和结果
   * - 第三方API请求和响应详情
   * - 算法执行过程和中间结果
   * 
   * 使用示例：
   * logger.debug('处理用户注册请求', {
   *   requestBody: req.body,
   *   validationResult: validationResult,
   *   processStep: 'validation_complete'
   * });
   * 
   * logger.debug('数据库查询执行', {
   *   query: 'SELECT * FROM users WHERE id = ?',
   *   params: [userId],
   *   executionTime: '25ms',
   *   resultCount: 1
   * });
   * 
   * 性能考虑：
   * - 调试日志可能包含大量详细信息
   * - 生产环境关闭调试日志可提高性能
   * - 避免在调试日志中包含敏感信息
   */
  debug: (message, ...args) => {
    // 仅在开发环境下输出调试日志 - Only output debug logs in development environment
    if (process.env.NODE_ENV === "development") {
      // 输出调试级别日志，包含时间戳和级别标识 - Output debug level log with timestamp and level identifier
      console.log(`[DEBUG] ${new Date().toISOString()} - ${message}`, ...args);
    }
  },

  /**
   * ============性能日志方法开始===========
   * 记录性能相关日志 - Log performance related messages
   * 
   * @param {string} message - 性能日志消息内容
   * @param {Object} metrics - 性能指标对象
   * @param {number} metrics.duration - 执行时间（毫秒）
   * @param {string} metrics.operation - 操作名称
   * @param {...any} args - 附加的性能参数
   * @returns {void} 无返回值
   * 
   * 功能说明：
   * - 专门记录性能相关的日志信息
   * - 用于监控和分析系统性能
   * - 包含执行时间、操作类型等关键指标
   * - 便于性能优化和问题排查
   * 
   * 使用示例：
   * const startTime = Date.now();
   * // ... 执行业务逻辑
   * const duration = Date.now() - startTime;
   * 
   * logger.performance('API请求处理完成', {
   *   duration: duration,
   *   operation: 'getUserProfile',
   *   endpoint: '/api/user/profile',
   *   method: 'GET'
   * });
   */
  performance: (message, metrics, ...args) => {
    // 输出性能日志，包含时间戳和性能指标 - Output performance log with timestamp and metrics
    console.log(`[PERF] ${new Date().toISOString()} - ${message}`, {
      duration: `${metrics.duration}ms`,
      operation: metrics.operation,
      ...metrics
    }, ...args);
  }
};

/**
 * ============日志工具导出说明开始===========
 * 导出日志记录器供应用使用
 * Export logger for application use
 * 
 * 导出说明：
 * - logger: 日志记录器对象，包含所有日志方法
 * 
 * 使用示例：
 * import { logger } from './utils/logger.js';
 * 
 * // 在控制器中使用
 * export const loginUser = async (req, res) => {
 *   try {
 *     logger.info('用户登录请求', { email: req.body.email });
 *     
 *     const user = await UserModel.findByEmail(req.body.email);
 *     if (!user) {
 *       logger.warn('登录失败：用户不存在', { email: req.body.email });
 *       return res.status(401).json({ message: '用户不存在' });
 *     }
 *     
 *     logger.info('用户登录成功', { userId: user.id });
 *     res.json({ success: true, user });
 *   } catch (error) {
 *     logger.error('用户登录异常', error);
 *     res.status(500).json({ message: '服务器错误' });
 *   }
 * };
 * 
 * // 在中间件中使用
 * export const requestLogger = (req, res, next) => {
 *   const startTime = Date.now();
 *   
 *   res.on('finish', () => {
 *     const duration = Date.now() - startTime;
 *     logger.performance('HTTP请求处理完成', {
 *       duration: duration,
 *       operation: 'http_request',
 *       method: req.method,
 *       url: req.originalUrl,
 *       status: res.statusCode
 *     });
 *   });
 *   
 *   next();
 * };
 * 
 * 最佳实践：
 * - 在关键业务节点记录信息日志
 * - 在异常处理中记录错误日志
 * - 在性能敏感操作中记录性能日志
 * - 避免在日志中记录敏感信息（密码、令牌等）
 * - 使用结构化数据便于日志分析
 */
export { logger };

// ============日志工具模块结束===========
